<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<HTML>
<HEAD>
<meta name="GENERATOR" content="Microsoft&reg; HTML Help Workshop 4.1">
<Title>Custom Transports</Title>
<link rel="STYLESHEET" type="text/css" href="styles.css">
</HEAD>
<BODY>
<h1>Writing new transports for PocketSOAP</h1>

PocketSOAP comes with HTTP and TCP transports. If you want to send and receive SOAP messages using a different transport, then its a fairly simple job to
interface your transport to pocketSOAP.
<ol>
<li>Build your transport object as a COM object.
<li>Implement the ISOAPTransport interface.
<li>Optionally implement the IHTTPTransport and/or ISOAPTransportTimeout interfaces.
</ol>

<h2>Build your transport object as a COM object.</h2>
PocketSOAP is COM based, for your transport to interact with PocketSOAP it needs to be a COM object [or you need a COM object that wraps your non COM API]

<h2>Implement the ISOAPTransport interface</h2>
<a href="ms-its:psdocs.chm::/interface_ISOAPTransport.html">ISOAPTransport</a> is a simple interface with just two methods Send and Receive.

<pre class="syntax">HRESULT Send([in] BSTR endpoint, [in] BSTR Envelope);</pre>

<p><b>endpoint</b> is a transport specific string that identifies who the recipient is, typically this is a URL, 
e.g. http://soap.example.com/soap.asp, jabber://4s4c@jabber.org/SoapServer etc.</p>
<p><b>Envelope</b> is the SOAP message to send. As this is a BSTR, it is a UTF-16 Unicode string. If your transport doesn't support UTF-16, or
if there is a more efficient encoding it can use, the transport can transcode the Envelope to another encoding [for HTTP it's transcoded to UTF-8]
</p>

<pre class="syntax">HRESULT Receive([in, out] BSTR * characterEncoding, [out, retval] SAFEARRAY(BYTE) * Envelope);</pre>

<p><b>Envelope</b> This is the response returned by the server as a result of the original call to Send. This is returned as an array of bytes, and can
be encoded in any encoding supported by the Expat XML parser (utf-8, utf-16, iso-8859-1, us-ascii).
<p><b>characterEncoding</b> In certain circumstances, the transport can override the encoding that the parse may decide from the payload. In this case
the transport should set the characterEncoding value to the name of the encoding to use. Otherwise it should set the characterEncoding to an empty string.
[HTTP transports compliant with <a href="http://www.normos.org/ietf/rfc/rfc2376.txt" target="_blank">RFC 2376</a> need this facility]

<p>If the transport does not directly support request/response semantics, then it is upto the transport object to main corellation-Ids between the request 
and the expected response.</p>

<h2>Optionally implement the IHTTPTransport interface</h2>

The <a href="ms-its:psdocs.chm::/interface_IHTTPTransport.html">IHTTPTransport</a> signals to other components that the transport follows the SOAP/HTTP binding semantics, 
this basically boils down to the use of  SOAPAction. If your transport supports the SOAPAction header [or equivilent for your transport], it should implement the 
IHTTPTransport interface which allows callers to set the value for SOAPAction.

<h2>Optionally implement the ISOAPTransportTimeout interface</h2>

The <a href="ms-its:psdocs.chm::/interface_ISOAPTransportTimeout.html">ISOAPTransportTimeout</a> interface signals to other components that the transport
supports user setable timeout values. If your transport supports timeouts, it shoudl implement this interface to signal that, and to allow the timeout value
to be changed.

<BR><BR><BR>
<h3>Copyright</h3>
<p>Copyright &copy; Simon Fell, 2000-2004. All rights reserved.<br>
</BODY>
</HTML>
